Cycle 18 — screenshots + GIFs of the running app (Playwright)

The last planned docs cycle. Adds the capture tooling and wires real image references into every "images coming" signpost. Because capturing the live app needs the operator's local stack (Docker + Wine + user-supplied .acs/voice files), this PR lands the scripts + docs wiring; the operator generates and commits the actual images.

Cycle spec: docs/cycles/cycle-18-screenshots.md · Decision: ADR-0028.

What's here

• scripts/capture/ — a Playwright script driving MASH (localhost:8090): loads a character, plays an animation, types into the balloon, triggers Speak, and saves stills (PNG) + GIFs. Pure-JS GIFs (element screenshots → pngjs → gifenc; no ffmpeg). Parameterized (--url/--acs/--name/--out/--speak/--animation/--smoke) and documented in scripts/capture/README.md.
• Docs wiring — real ![alt](assets/…) references in README, docs landing, install ×3, what-is-this, characters, and the developer overview/quickstart, at the correct relative depth.
• ADR-0028 — screenshots/GIFs of the running app are committable documentation, distinct from (and not loosening) ADR-0006's ban on committing .acs/binaries.

What the operator runs (then commits)

docker compose up                              # MASH :8090 (+ voice :8080 for the talking shots)
pnpm capture:setup                             # once — installs Chromium
pnpm capture -- --acs /path/to/Genie.acs       # writes assets/screenshots/* and assets/gifs/*
git add assets/screenshots assets/gifs && git commit

Until those files are committed, the new image references 404 on GitHub — expected; merge after they land.

IP hygiene

No .acs or binaries committed (*.acs/*.wav still gitignored). The script reads the operator's .acs by path only — never writes it — and bakes in no proprietary download.

Verification

• pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format — all green (new deps + script).
• --smoke passed against a live MASH dev server — headless Chromium launched and all 7 selectors resolved against the real DOM. The GIF encoder runs end-to-end (valid output). code-reviewer verified script correctness, IP hygiene, and image-path depths.

Honest boundary

CC can run Playwright headless (validated), but has no .acs and no Wine/authentic voice, so CC does not produce the real images — the operator does. Tell CC if a shot needs a specific character/animation loaded.

Out of scope

Nothing after this (last planned docs cycle). No app/@vivify/core change. No merge.

🤖 Generated with Claude Code